• If using a debugger that requires DebugServices — such as the Apple debuggers or the CodeWarrior 6 debugger — make sure the correct version of DebugServices is running, otherwise you may crash. For 68K Macs, the latest version is 2.0a6. For Power Macs, the current version is 2.0. (The CodeWarrior 7 debugger normally uses its own debugger nub, MetroNub. If you choose to use DebugServices instead, make sure you disable the MetroNub extension and reboot.)
• Needless to say, you should also have MacsBug installed. The current version, included here, is 6.5.2. It has excellent support for PowerPC debugging, including stack crawls.
Part editor setup.
• Make sure the editor library, or an alias to it, is in the Editors folder. This folder can be in the active System folder, or at the root level of any mounted disk. While developing, it's convenient to leave the editor in the development folder where the linker puts it, and put an alias into the Editors folder.
• Make sure the editor's .SYM or .xSYM file is in the same folder as the editor.
• The 'cfrg' resource must contain two entries with two different names. The long name must be the same as the System Object Model™ (SOM) classname (of the form "module::class") of the library. The short name must be the same as the suffix of the SOM classname (just the "class" part.)
• The sym file name must be the short 'cfrg' name with “.xSYM” (PPC) or ".SYM" (68k) appended.
• The filename of the library must be the same as the short 'cfrg' name, if you are using the Metrowerks debugger. This shouldn't be a requirement, but we've had trouble getting the debugger to work if it's not set up this way. It may be a debugger bug; it's been reported to Metrowerks.
Example: The part editor whose SOM class name is Jens::TSamplePart lives in a CFM library whose names in the 'cfrg' resources are Jens::TSamplePart and TSamplePart, and whose filename is also TSamplePart. The PPC sym file is named TSamplePart.xSYM or TSamplePart.SYM.
Warning: The Sample Code parts provided on this CD do not adhere to the file naming scheme as listed in the last two bullet items. To debug these parts using the Apple or Metrowerks debuggers, you must first rename the part editor and the sym file based on the part's SOM classname. Example: The SOM classname of SamplePart is som_SamplePart. So you should rename the library som_SamplePart and the sym file som_SamplePart.SYM or som_SamplePart.xSYM. Of course, you only need to do this when you are debugging. In normal use it does not matter what the library's filename is.
Debugging the part — Method 1
•Open your editor's sym file with the appropriate debugger. (If your library was built with CodeWarrior you can just double-click the sym file.)
•Set a break point or two. InitPart and InitPartFromStorage are usually a good places to start.
•Hold down the Control key and double-click a stationery pad or document containing an instance of your part. (If you want to generate stationery — debugging your InitPart method, eh? — hold down Control and drop your editor's library file onto the "OpenDoc™" launcher app.) Keep the control key down until the debugger opens a window on your part. [If using the CodeWarrior 7 debugger with the MetroNub, you do not need to hold down the Control key when launching.]
• Depending on circumstances, the debugger may stop before it hits your breakpoint (the Apple debugger tends to stop immediately after launching the process.) If so, choose Run.
•Now, you can go ahead and step, run, set more breakpoints etc. Have a party.
NOTE: There's a bug in the 68k Macintosh Debugger that can prevent it from targeting when it hits a breakpoint. The debugger will target when it hits a Debugger or DebugStr instruction, though. As a workaround of sorts, the OpenDoc shell will call DebugStr as soon as it initializes itself if the Option key is held down. When debugging on 68k you may want to hold down the Option key as the shell comes up to get that debugstr so the debugger will target your library properly.
Debugging the part — Method 2
If you use the Apple debugger, or version 1.1.1 or later of the Metrowerks debugger, you can launch the document normally and then target it with the debugger after it's launched. Of course, this won't work for debugging your initialization/internalization code.
• Launch a document or stationery pad containing an instance of your part.
•Open your editor's sym file with the appropriate debugger. (If your library was built with CodeWarrior you can just double-click the file.)
• Target the document's process with the debugger. In the Metrowerks debugger, open the Processes window and click at the left of the line showing the name of the document. In the Apple debugger, choose Show Tasks from the Views menu, select the document process, then choose Target from the Control menu.
• Now you can set breakpoints in your code.
Important limitations.
•Due to some System Software / DebugServices details we won't get into here, loading shared libraries in the midst of a drag-n-drop operation while the process is targeted by the debugger will cause a very hard crash. The Metrowerks debugger version 1.2 tries to get around this problem, and largely succeeds, but will sometimes still crash in these circumstances.
What this means is that if you drop something into a document, and it causes a part to be instantiated, no instances of which previously existed in that document, you'd better not be debugging that document. A fine instance of this is dragging part stationery into a document. There are several workarounds:
1. Use debugging method 2 above and target the document process only once the drag is completed. (This won't help you debug your editor's initialization code, however.)
2. Without running the debugger, make and open a ContainerPart document and drop your part stationery into it. Close and save the document. Now you can use the debugger on that document, which has your part pre-loaded in it.
3. Use some other means than drag-n-drop to embed your part, such as the Insert command on the Document menu, if the container supports this. (The Container part supports a skanky Insert command in its View menu for just this purpose.)
• The CodeWarrior debugger cannot show code that it doesn't have a SYM file for, not even as an assembly view. You won't be able to step into OpenDoc code unless you have the SYM files (and hopefully the source) for OpenDoc; and you have to have the appropriate SYM file open in the debugger before stepping in. (There may or may not be a procedure for requesting the OpenDoc DR3 source code from Apple. Check the Licensing Information folder at the root of the CD. Source code will be available for the final 1.0 release of OpenDoc.)
Stepping into a SOM call is a bit weird, since there's some glue in the way. The Metrowerks debugger will automatically step over the glue. The Apple debugger won't; when you step into a SOM call you will have to wade through about 15 assembly instructions before you pop out on the destination side. Keep using the Step In command until you emerge. You may have to manually set the view back to Source from Assembly; it helps if you already have a window showing the target method.
